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PAK: 


A  PROCESSING  SYSTEM  FOR  VECTORIZED  TIME-SERIES  DATA 


INTRODUCTION 

PAK  evolved  from  a  sequence  of  analysis  systems  having  their 
genesis  in  a  system  called  FESTSA  [1].  The  original  system  was 
designed  to  run  on  a  UNIVAC  1108  mainframe  computer  using  disk 
packs  and  9-track  tape  for  off-line  storage.  The  objective  of 
the  file  system  was  to  eliminate  the  need  for  separately  named 
files  for  each  data  set  by  creating  a  number  of  time  series  in 
the  same  disk  file.  The  series'  were  stored  sequentially  and 
routines  were  written  to  store  new  series  and  delete  old  series 
to/from  each  file. 

A  later  version  of  FESTSA,  called  RUSPAC  [2]  was  developed  at 
Nova  University,  which  added  a  "Delete  Disk,"  a  temporary  disk 
storage  area  which  was  created  at  the  beginning  of  a  session  and 
deleted  at  the  end.  Off-line  storage  was  on  disk  packs  and  tape 
called  "Keep  Disks"  and  "Keep  Tapes"  to  distinguish  them  from  the 
Delete  Disks.  The  user  implemented  his  own  routines  by 
communicating  the  data  to  and  from  existing  routines  via  a  named 
common  area  called  "CSER. " 

PAK  differs  from  these  earlier  packages  in  that  it  uses  an 
established  high  level  language  and  library  of  routines  for 
analysis,  called  "MATLAB"  and  an  established  plotting  and 
analysis  package  called  "ORIGIN"  [3,4].  PAK  runs  on  a  personal 
computer  under  Microsoft  Windows  rather  than  on  a  mainframe 
computer.  In  PAK,  the  user  communicates  data  to  and  from  storage 
devices  and  other  routines  through  MATLAB  variables.  PAK  also 
makes  use  of  a  Graphical  User  Interface  to  make  analysis 
interactive  and  easier  to  use.  PAK  still  retains  the  ability  of 
the  earlier  systems  to  run  in  a  "batch"  mode  by  storing  a 
sequence  of  key  strokes  in  a  script  file.  The  script  file  is 
then  run  as  a  batch  file.  See  Fig.  1  for  PAK  data  flow  diagram. 

An  individual  time  series  is  composed  of  a  header  record  followed 
by  many  data  records.  The  header  record  contains  the  start  time, 
expressed  in  seconds  from  Jan  1,  1968,  the  data  interval  in 
seconds,  the  number  of  data  points  in  the  series,  the  ID  Number 
of  the  Pak  function  that  produced  the  series,  if  such  was  the 
case,  the  date  the  function  produced  the  series,  and  an  ASCII 
message,  which  can  describe  the  conditions  under  which  the  data 
were  collected  (e.g.,  type  of  data,  experiment  name,  location, 
date,  etc.).  The  data  can  be  integer,  real,  or  complex. 

A  number  of  related  time  series'  are  stored  in  a  data  file  — 
either  a  permanent  file,  a  temporary  file  called  the  "delete 


1 


Figure  1.  PAK  Data  Flow 


disk,"  or  reside  in  memory  called  "core."  Each  file  has  a  header 
record  composed  of  an  ASCII  header  message  only.  This  message  is 
intended  to  contain  a  general  description  of  the  series* 
contained  within  the  data  file.  For  example,  a  data  file 
containing  time  series'  taken  from  a  current  meter  deployed 
during  the  HI-RES  experiment  might  contain  the  header  record 
message,  "Current  meter  data  collected  at  30.1°  N,  72.5°  W,  from 
2  Jul  93  to  15  Aug  93,  during  the  HI-RES  experiment." 

SETUP 


To  use  the  PAK  functions  the  script  files  must  be  accessible  to 
the  system.  The  suggested  directory,  for  the  copy  of  these 
files,  is  \matlab\toolbox\pak\.  The  path  variable  for  MATLAB 
must  be  modified  to  search  this  directory.  The  user  can  type  the 
command  to  add  this  directory  to  the  search  path  during  the 
MATLAB  session;  the  command  to  add  this  directory  to  the  search 
path  can  be  included  in  the  startup. m  file;  or  it  can  be  defined 
in  matlabrc.m  [3]. 

The  system  has  two  data  files  that  the  user  can  elect  to  modify 
using  any  text  editor.  The  file  dirlist.dat  contains  the  list  of 
valid  data  directories  for  PAK  to  locate  series  data  files.  The 
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file  funclist.dat  contains  a  list  of  functions  that  can  be  used 
to  process  data  series.  For  each  function  this  file  will  contain 
three  records.  The  first  record  contains  the  *.m  file  name  for 
the  function.  The  second  record  contains  the  label  for  creating 
the  menu  option  to  select  the  function.  The  third  record  contains 
the  number  of  series  required  as  input  for  the  function.  These 
two  files  allow  the  user  to  customize  the  PAK  program. 


RUNNING  PAK 

The  PAK  program  has  two  optional  command  line  arguments.  The 
first  selects  the  run  mode  and  the  second  defines  the  parameter 
file  for  reading  or  writing.  The  command  to  initiate  the  PAK 
program  is  as  follows: 

pak  [(run  mode),  [parameter  file])] 

The  default  run  mode  is  0;  if  required  the  default  parameter  file 
is  batch.dat.  The  run  mode  defines  how  the  user  will  interact 
with  the  program  and  if  a  parameter  file  will  be  used  for  input 
or  will  be  created.  The  run  modes  are  as  follows: 

0  . .  mouse  driven  menu 

1  . .  keyboard  driven  menu 

2  . .  batch  processing;  parameter  file  used  for  all  inputs 

3  . .  mouse  driven  menu,  output  a  parameter  file  of  all  user 

inputs  including  menu  responses  for  later  use  in  mode  2 

4  . .  keyboard  driven  menu,  output  a  parameter  file  of  all  user 

inputs  including  menu  responses  for  later  use  in  mode  2 

For  modes  0  and  3  most  of  the  user  interaction  will  be  via  the 
mouse  with  some  keyboard  input  required.  For  modes  1  and  4  the 
menu  options  will  be  selected  using  the  keyboard  with  some  other 
keyboard  inputs  required.  Mode  2  is  the  noninteractive  mode. 

All  inputs  including  menu  responses  are  read  from  the  input 
parameter  file.  Care  should  be  used  with  this  mode,  since  files 
and  series  are  selected  by  their  position  in  the  list.  The 
parameter  file  is  an  ASCII  file.  It  can  be  created  by  the  user 
with  a  text  editor  or  by  a  previous  run  of  the  PAK  program  using 

mode  3  or  4.  The  file  can  be  modified,  as  well  as  created  using 

a  text  editor.  This  mode  is  provided  to  allow  the  user  to  do 
repeat  processing.  If  the  user  saves  a  parameter  file  using  mode 

3  or  4  and  then  reruns  the  program  using  the  same  parameter  file, 

then  the  processing  will  be  performed  exactly  as  it  was  when  the 
user  operated  the  system  using  mode  3  or  4.  The  parameter  file 
can  be  modified  to  change  the  input  file  name  or  the  series 
selection.  This  allows  the  user  to  process  multiple  series  of  a 
file  or  different  files  as  needed  without  running  the  PAK  program 
interactively . 

PAK  uses  3  types  of  data  storage  for  series  data:  input/ output 
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files,  a  working  file  (called  the  delete  disk) ,  and  core 
(internal  program  memory) . 

Input/output  files  must  reside  in  one  of  the  directories  defined 
in  the  dirlist.dat  file.  The  selection  can  be  altered  by 
changing  the  dirlist.dat  file  as  needed.  This  file  is  an  ASCII 
file.  It  contains  one  entry  for  each  directory  to  be  included  in 
the  list  of  valid  data  directories.  The  entries  will  be  read 
and  the  characters  '\hd'  or  '  hd*  will  be  added  to  the  file 
directories  to  form  file  prefixes.  All  file  names  must  begin 
with  the  character  'hd'  and  contain  five  alphanumeric  characters. 
The  first  menu  of  the  system  contains  the  list  of  valid  file 
prefixes.  A  sample  menu  follows: 


OPEN  FILES 

Keyboard 

input 

a : \pak\hd 

1 

b:\pak\hd 

2 

c : \pak\hd 

3 

d : \pak\hd 

4 

e : \pak\hd 

5 

QUIT 

0 

See  appendix  B  for  the  dirlist.dat  file  used  to  create  this  menu. 
The  user  selects  the  menu  option  and  is  prompted  for  the 
remainder  of  the  file  name,  for  example  if  the  first  prefix  is 
chosen,  then  the  prompt  is  as  follows: 

COMPLETE  FILE  NAME  a:\pak\hd 

The  user  must  supply  the  five  alphanumeric  characters  to  complete 
the  file  name.  Each  file  can  be  opened  only  once.  If  the  file 
does  not  exist,  then  it  will  be  created.  When  all  file  names 
have  been  input  the  user  selects  QUIT  to  continue  to  the  next 
step.  If  the  user  enters  an  invalid  response  or  nothing  at  the 
file  input  prompt,  then  a  message  will  appear  and  control  returns 
to  the  menu. 

Once  all  file  names  have  been  input  a  test  is  made  to  determine 
if  the  delete  file  from  a  previous  run  is  available.  If  yes, 
then  the  user  is  prompted. 

delete.dat  ..  keep  or  delete  [ D] ? 

If  delete  is  chosen,  the  default  is  delete,  then  a  new  empty 
delete  disk  file  is  created.  If  the  user  selects  keep,  then  the 
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file  will  be  opened  and  used  as  is. 

The  files  input  by  the  user  are  tested.  If  the  file  does  not 
exist,  then  it  will  be  created.  A  newly  created  file  will 
contain  a  blank  header  record,  an  end  of  series  record,  and  an 
end  of  file  record.  See  Appendix  A  for  an  explanation  of  these 
records.  Input  files  are  tested  for  premature  end  of  series, 
premature  end  of  file,  or  invalid  change  in  series  number.  The 
file  may  have  been  corrupted  due  to  a  power  shutdown  during  a 
write  procedure  or  some  other  unexpected  exit.  If  a  correctable 
error  is  found  then  the  user  will  have  the  option  of  fixing  the 
file.  The  prompt  for  this  fix  is  as  follows: 

Fix  file  ..  fname  (def:Y  or  N)  - 

Where  fname  is  the  name  of  the  problem  file.  The  fix  will  be 
done  by  truncating  the  file  at  the  end  of  the  last  valid  series. 

Once  all  files  have  been  opened  and  the  program  initialized,  the 
user  is  presented  with  the  main  menu. 


PAK 

Keyboard 

input 

File  Header 

1 

Directory 

2 

Copy 

3 

Delete 

4 

Series 

5 

Create  new  series  number 

6 

Functions 

7 

MATLAB  command 

8 

Output 

9 

QUIT 

0 

This  menu  is  the  system  manager.  Each  option  will  be  discussed 
in  full.  There  are  three  menus  that  are  often  used  by  multiple 
functions  of  PAK.  These  are  described  below.  The  first  selects 
the  type  of  data  storage  to  be  used  by  a  function. 
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TITLE 

Keyboard 

input 

CORE 

1 

FILE 

2 

QUIT 

0 

TITLE  changes  with  the  selected  application.  The  QUIT  option 
will  stop  the  function.  CORE  means  the  user  will  be  using  core 
data;  FILE  means  the  user  will  be  selecting  a  series  from  the 
delete  disk  or  one  of  the  other  input/ output  files. 

When  FILE  is  selected  then  a  file  selection  menu  will  be  given. 
An  example  of  a  file  select  menu  is  as  follows: 


FILES 

Keyboard 

input 

DELETE  DISK 

1 

c:\pak\hdl2345 

2 

c:\pak\hd88877 

3  i 

a:\pak\hd33445 

4 

QUIT 

0 

This  menu  will  vary,  each  file  the  user  opened  at  the  beginning 
of  the  program  run  will  be  listed.  If  the  number  of  input  files 
cannot  be  contained  within  a  single  menu  on  the  screen  and  the 
menu  is  mouse  driven,  then  multiple  menus  will  be  used  to 
display  file  names.  PREV  and  NEXT  will  be  used  to  change  menus. 
The  menu  list  is  circular.  If  PREV  is  selected  on  the  first 
menu,  then  the  last  menu  will  be  displayed.  If  NEXT  is  selected 
on  the  last  menu,  then  the  first  menu  will  be  displayed. 

For  some  applications  once  the  CORE  option  or  a  file  is  selected 
then  the  menu  for  selecting  a  series  will  be  displayed.  This 
menu  will  vary  for  the  list  of  series  in  core  or  the  selected 
file.  The  scheme  described  above  for  multiple  menus  will  be  used 
when  required  for  a  series  list.  An  example  of  a  series  menu  is 
as  follows: 
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SERIES  . .  CORE 

Keyboard 

input 

PREV 

not  used 

(1) 

26410 

1 

(2) 

26415 

2 

(3) 

26420 

3 

(4) 

26425 

4 

(5) 

26430 

5 

(6) 

20065 

6 

(7) 

20075 

7 

NEXT 

not  used 

QUIT 

0 

The  three  menus  described  above  will  be  used  often,  and  we  will 
refer  to  them  as  select  core/file  menu,  select  file  menu,  and 
select  series  menu. 

File  Header 


The  File  Header  option  of  the  main  menu  allows  the  user  access  to 
the  header  record  of  any  of  the  opened  data  files.  When  this 
option  is  selected  the  file  select  menu  will  be  displayed  for  the 
user  to  select  the  desired  file.  Once  a  file  is  selected,  the 
file  header  menu  will  be  displayed  as  follows: 


File  Header 

Keyboard 

input 

List 

1 

Create 

2 

Append 

3 

QUIT 

0 

If  List  is  chosen,  then  the  header  of  the  selecteu  file  will  be 
displayed  for  the  user.  See  Appendix  C  for  an  example.  If 
create  is  chosen,  then  the  user  will  be  given  the  following 
prompt : 
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msg> 

At  this  prompt  the  user  creates  a  new  ASCII  header  for  the 
selected  file.  The  prompt  will  be  repeated  until  the  user 
presses  <return>  only  at  the  prompt.  The  header,  if  too  long, 
will  be  truncated  to  fit  the  size  of  the  header  record.  If  the 
Append  option  is  chosen,  then  the  user  will  again  see  the  prompt: 

msg> 

This  time  the  information  entered  by  the  user  will  be  added  to 
the  header  record  starting  after  the  last  nonblank  character  of 
the  existing  header.  Again  the  prompt  will  be  repeated  until 
<return>  is  the  only  response  at  the  prompt.  The  file  header 
menu  will  be  displayed  after  each  selection  until  QUIT  is 
selected. 

Directory 

The  directory  option  of  the  main  menu  will  allow  the  user  to  do  a 
directory  listing  of  the  series  in  core  or  of  a  selected  file. 

The  user  will  get  the  select  core/file  menu  and  if  file  is 
selected  then  the  select  file  menu  will  be  displayed  for  the 
user's  response.  Once  the  selection  is  made,  a  directory  listing 
will  be  displayed.  See  Appendix  D  for  an  example.  The  list 
includes  series  number,  number  of  data  values,  data  type,  start 
time  (or  value) ,  time  interval  for  data  values,  function 
identification  number,  function  date  (if  function  identification 
number  is  not  zero) ,  and  series  annotation. 

Copy 

The  copy  option  allows  the  user  to  copy  a  series  from  one  storage 
medium  to  another.  The  menu  for  copy  is  as  follows: 


Copy 

Keyboard 

inputs 

File  to  Core 

1 

Core  to  File 

2 

Core  to  Delete 

3 

Delete  to  Core 

4 

Delete  to  File 

5 

File  to  Delete 

6 

QUIT 

0 
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For  the  file  to  core  copy  the  user  must  respond  to  select  file 
and  select  series  menus.  The  select  file  menu  will  not  contain 
the  DELETE  DISK  option  for  this  application.  Also,  the  user  will 
be  allowed  to  filter  the  data  when  it  is  copied.  The  filter  menu 
is  as  follows: 


FILTERS 

Keyboard 

input 

time 

1 

index 

2 

NONE 

0 

If  the  time  option  is  selected,  then  the  user  will  be  prompted 
for  start  time  as  follows: 

Enter  start  time  as  date  (def:Y  or  N)  - 

for  No  the  user  is  prompted 

Enter  start  time  as  single  value  (def:  ?)  - 

for  Yes  the  user  is  prompted 

Start  year  (def:  ?)  - 
Start  month  (def:  ?)  - 
Start  day  (def:  ?)  - 
Start  hour  (def:  ?)  - 
Start  minute  (def:  ?)  - 
Start  second  (def:  ?  )  - 

In  each  case  the  default  is  the  start  time  (or  value)  of  the  data 
to  be  copied.  Also,  the  user  is  prompted  for  length  of  time: 

Length  of  time  in  seconds  (def:  ?)  - 

The  default  will  be  for  the  length  of  time  required  to  copy  all 
data  after  the  user  specified  start  time. 

If  the  index  option  is  selected,  then  the  user  will  be  prompted 
for  the  following: 

Start  index  (def:  1)  - 
Sub-sampling  increment  (def:  1)  - 
End  index  (def:  ?)  - 

The  default  for  the  ending  index  will  be  the  number  of  data 
values  in  the  series.  Starting  at  the  specified  start  index 
every  data  value  will  be  copied  for  an  increment  of  1,  every 
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other  data  value  for  an  increment  of  2,  etc.,  to  the  specified 
end  index. 

The  data  is  copied  as  specified  by  the  selected  filter  or  all 
data  is  copied  if  NONE  is  the  selected  filter.  If  needed  the 
series  header  values  for  start  time  and  time  increment  are 
adjusted  for  the  filtering.  Each  of  the  filters  has  a  function 
identification  number  associated  with  it.  Zero  for  NONE;  one  for 
time;  and  two  for  index.  When  filtering  is  used,  the  date  for 
the  data  creation  (copy)  is  stored  in  the  function  date  portion 
of  the  series  header. 

For  the  core  to  file  copy  option  the  user  must  respond  to  the 
select  series  menu  to  select  the  core  series  to  be  copied,  and 
the  user  must  respond  to  the  select  file  menu  for  the  file  to 
contain  the  copied  series.  The  select  file  menu  will  not  contain 
the  DELETE  DISK  option.  No  filtering  is  allowed.  The  series 
will  be  appended  to  the  end  of  the  selected  file. 

For  the  core  to  delete  copy  option  the  user  must  respond  to  the 
select  series  menu  to  select  the  core  series  to  be  copied.  No 
filtering  is  allowed.  The  series  will  be  appended  to  the  end  of 
the  delete  disk  file. 

For  the  delete  to  core  copy  option  the  user  must  respond  to  the 
select  series  menu  to  select  the  delete  disk  series  to  be  copied. 
Filtering  is  allowed,  see  option  for  copy  from  file  to  core  for 
filtering  menu  and  prompts.  The  filtering  is  applied  in  the  same 
way.  The  copied  series  will  be  appended  to  the  end  of  the  core 
list. 

For  the  delete  to  file  copy  option  the  user  must  respond  to  the 
select  series  menu  to  select  the  delete  disk  series  to  be  copied 
and  the  user  must  respond  to  the  select  file  menu  for  the  file  to 
contain  the  copied  series.  The  DELETE  DISK  option  will  not 
appear  as  an  option  in  the  select  file  menu.  The  series  will  be 
appended  to  the  end  of  the  selected  file.  No  filtering  is 
allowed. 

For  the  file  to  delete  copy  option  the  user  must  respond  to  the 
select  file  and  select  series  menus  to  select  the  series  to  be 
copied.  The  selected  series  is  copied  from  the  selected  file  and 
will  be  appended  to  the  end  of  the  delete  disk  file.  No 
filtering  is  allowed. 

Delete 

The  delete  option  of  the  main  menu  will  allow  the  user  to  delete 
a  series  from  core  or  from  a  selected  file.  The  user  will  get 
the  select  core/file  menu.  If  file  is  selected,  then  the  select 
file  menu  will  be  displayed  for  the  user's  response.  Finally  the 
select  series  menu  will  be  displayed  for  the  selected  file  or 
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core  series  list.  When  the  user  selects  a  series  front  the  menu, 
that  series  is  deleted  from  core  or  the  selected  file  as 
specified  by  the  user. 

Series 

The  series  option  of  the  main  menu  allows  the  user  to  view  series 
data  and  header  information,  alter  a  series  header  annotation, 
and  change  the  series  number (s) .  The  user  will  get  the  select 
core/file  menu.  After  which  the  menu  for  series  will  be 
displayed  as  follows: 


SERIES  OPERATIONS 

Keyboard 

input 

Series  Header 

1 

View  Data 

2 

Change  Series  Number 

3 

Resequence 

4 

QUIT 

0 

For  the  series  header  option  the  select  series  menu  will  be 
displayed  for  the  user's  response.  The  menu  for  series  header  is 
as  follows: 


SERIES  HEADER 

Keyboard 

input 

List 

1 

Create  Information 

2 

Append  Information 

3 

QUIT 

0 

If  list  is  the  chosen  option,  then  the  header  information  for  the 
selected  series  will  be  displayed.  See  Appendix  E  for  an 
example.  The  create  and  append  options  are  used  to  modify  the 
information  area  contained  within  the  series  header.  The 
prompting  for  these  will  be  the  same  as  that  described  for  the 
main  menu  File  Header  options  create  and  append. 

For  the  view  data  option  the  select  series  menu  will  be  displayed 
for  the  user's  response.  The  user  will  then  be  prompted  as 
follows: 
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Specify  start  (def:  1)  - 
Specify  increment  (def:l  )  - 
Specify  end  (def:  ?)  - 

The  default  for  the  ending  index  will  be  the  number  of  data 
values  contained  in  the  selected  series  or  the  number  required 
for  printing  10  data  values,  the  smaller  of  these  two  values  will 
be  chosen.  Starting  at  the  specified  start  index  every  data 
value  will  be  displayed  for  an  increment  of  1,  every  other  data 
value  for  an  increment  of  2,  etc.,  to  the  specified  end  index. 

The  display  will  include  the  index,  time  value,  and  data  value 
for  the  specified  range.  See  Appendix  F  for  an  example.  After 
the  display  the  user  is  prompted: 

More  (def:Y  or  N) 

If  yes,  then  the  user  will  be  prompted  for  the  index  values  again 
and  the  specified  data  will  be  displayed.  If  no,  then  control 
returns  to  the  series  operations  menu. 

If  change  series  number  is  the  chosen  option,  then  the  select 
series  menu  will  be  displayed  for  the  user's  response.  The 
series  number  for  the  selected  series  will  be  changed  to  the 
current  default  new  series  number. 

If  resequence  is  the  selected  option  then  all  the  series 
contained  within  core  or  the  selected  file  will  be  assigned  new 
consecutive  series  numbers.  The  numbering  will  start  with  the 
current  new  series  number  and  be  incremented  by  the  current  new 
series  number  increment. 

Create  New  Series  Number 

The  create  new  series  number  option  allows  the  user  to  change  the 
new  series  number  and  new  series  number  increment.  The  new 
series  number  is  assigned  for  newly  created  series,  the  exception 
is  copy  with  no  filtering,  then  the  original  series  number  is 
retained.  The  new  series  number  increment  is  used  to  increment 
the  new  series  number  after  each  use.  These  values  are  also  used 
for  changing  a  series  number  and  resequencing  series  stored  in 
core  or  a  selected  file.  The  prompts  for  the  user  are  as 
follows: 

Series  number  (def:  ?)  - 
Series  increment  (def:  ?)  - 

The  current  values  will  be  the  defaults.  The  initial  values  for 
these  are  a  random  number  for  the  new  series  number  and  10  for 
the  increment. 
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Functions 


The  functions  option  of  the  main  menu  allows  the  user  to  create 
data  series  for  core.  The  menu  for  functions  is  as  follows: 


FUNCTIONS 

Keyboard 

input 

Create  core  data 

1 

User  function 

2 

Filters 

3 

FUNCTION 1 

4 

• 

• 

• 

• 

• 

• 

FUNCTIONn 

n+3 

QUIT 

0 

FUNCTI0N1,  ...  FUNCTIONn  are  defined  in  the  funclist.dat  file. 

The  funclist.dat  file  contains  the  '.m'  file  name,  menu  option 
definition  (FUNCTI0N1,  ...,  FUNCTIONn),  and  the  number  of  data 
series  required  for  the  function.  See  Appendix  G  for  an  example 
funclist.dat  file. 

The  create  core  data  option  allows  the  user  to  create  core  series 
using  MATLAB  commands.  This  is  the  most  common  method  of 
converting  data  having  arbitrary  format  to  a  PAK-formatted  time 
series.  When  this  option  is  chosen,  the  message  and  prompt  to 
the  user  is  as  follows: 

Use  MATLAB  commands  to  create  data  (return  allows  save  data 
or  type  'QUIT1  for  return  to  menu) 

cmd> 

The  cmd>  prompt  repeats  for  the  user  to  enter  and  execute  MATLAB 
commands.  These  commands  might  include  reading  data  from  a  file. 
To  exit  this  mode  press  <return>  at  the  prompt;  typing  QUIT 
returns  the  user  to  the  functions  menu  and  no  new  series  is 
created.  When  <return>  is  pressed,  the  screen  prompts  the  user 
to  define  the  variable  containing  the  series  data: 

Provide  variable  name  containing  data  - 

If  the  user  does  not  enter  a  variable  name  or  there  is  a  problem 
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with  the  variable,  then  control  returns  to  the  cmd>  prompt.  This 
allows  the  user  to  check/alter  the  data.  As  before,  the  user 
presses  <return>  to  continue  or  types  QUIT  to  exit  this  mode  and 
returns  to  the  functions  menu.  Once  the  variable  name  containing 
the  series  data  values  has  been  provided,  the  user  must  provide 
the  required  header  information.  The  following  menu  is  used  to 
define  the  data  type.  Data  type  is  used  only  if  the  data  series 
is  later  written  to  an  output  file: 


Data  Type 

Keyboard 

input 

inti  6 

1 

int32 

2 

f  lt32 

3 

f  lt64 

4 

comp 3 2 

5 

comp64 

6 

The  user  must  supply  start  time,  time  interval,  and  if  desired 
series  annotation  information.  The  prompts  for  this  information 
are  as  follows: 

Enter  start  time  as  date  (def:Y  or  N)  - 

for  No  the  user  is  prompted 

Enter  start  time  as  single  value  (def:  0)  - 

for  Yes  the  user  is  prompted 

Start  year  (def:  ?)  - 
Start  month  (def:  ?)  - 
Start  day  (def:  ?)  - 
Start  hour  (def:  ?)  - 
Start  minute  (def:  ?)  - 
Start  second  (def:  ?  )  - 

The  default  for  the  date  and  time  is  the  current  date/time. 

Data  interval  (seconds)  - 
Series  Annotation  (opt.). 
msg> 

The  msg>  prompt  will  be  repeated  until  only  <return>  is  pressed. 
This  information  will  be  truncated  if  the  message  is  longer  than 
200  bytes. 
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The  user  function  option  allows  the  user  to  create  new  core 
series  data  using  existing  core  series  data  and  MATLAB  commands. 
When  this  option  is  chosen,  the  select  series  menu  will  be 
displayed  for  the  user.  The  user  selects  one  or  more  core 
series,  the  QUIT  option  closes  this  menu.  The  series  data  and 
associated  time  labels  are  stored  in  variables  that  will  be 
listed  for  the  user.  An  example  of  this  listing  is  as  follows: 

dl  (core  data  for  series:  26406) 
tl  (core  times  for  series:  26406) 
d2  (core  data  for  series:  26400) 
t2  (core  times  for  series:  26400) 

The  variable  dl,  tl,  d2,  and  t2  are  now  available  for  use  with 
MATLAB.  As  with  create  core  data  the  prompt  to  the  user  is  as 
follows: 

Use  MATLAB  commands  to  create  data  (return  allows  save  data 
or  type  'QUIT'  for  return  to  menu) 

cmd> 

The  cmd>  prompt  repeats  for  the  user  to  enter  and  execute  MATLAB 
commands.  These  commands  can  use  the  variables  containing  the 
selected  series  data  and  times.  To  exit  this  mode  press  <return> 
at  the  prompt;  typing  QUIT  returns  the  user  to  the  functions  menu 
and  no  new  series  is  created.  The  QUIT  option  is  useful  for  when 
the  user  simply  wishes  to  manipulate  or  plot  the  data  without 
creating  a  new  series.  When  <return>  is  entered,  the  screen 
prompts  the  user  to  define  the  variable  containing  the  series 
data: 


Provide  variable  name  containing  data  - 

If  the  user  does  not  enter  a  variable  name  or  there  is  a  problem 
with  the  variable,  then  control  returns  to  the  cmd>  prompt.  This 
allows  the  user  to  check/alter  the  data.  As  before  the  user 
presses  <return>  to  continue  or  types  QUIT  to  exit  this  mode  and 
return  to  the  functions  menu.  Once  the  variable  name  containing 
the  series  data  values  has  been  provided,  the  user  must  define 
the  header  information.  The  user  has  the  option  of  defaulting  to 
the  data  type,  start  time,  and  time  interval  of  the  first  series 
selected  or  these  values  can  be  specified  by  the  user.  The 
prompt  for  the  user  is  as  follows: 

Keep  header  attributes  of  series:  ?  (def:Yes)  - 

For  this  example  ?  will  be  26406,  the  first  series  selected.  If 
yes  is  selected,  then  the  user  will  be  prompted  for  the  optional 
series  annotation  information: 

Series  annotation (opt. ) . 
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msg> 


For  more  information  about  this  prompt  see  the  description  for 
create  core  data.  If  no  is  selected  for  keep  header  attributes, 
then  the  user  will  be  prompted  for  the  required  information.  For 
a  description  of  the  prompts  for  the  required  header  information 
see  the  discussion  for  create  core  data.  The  assigned  function 
number  will  be  999,  for  user  functions. 

The  Filters  option  allows  the  user  to  create  a  new  series  for 
core  by  filtering  an  existing  core  series.  For  this  option  the 
select  series  menu  will  be  displayed  for  the  user's  response. 

Once  a  series  is  selected  the  filters  menu  will  be  presented. 

See  the  file  to  core  option  of  the  copy  menu  for  a  description  of 
the  filters  menu,  prompts,  and  the  discussion  of  the  available 
filters. 

The  option  of  FUNCTIONm  (m  =  an  integer  from  1  to  n  where  n  is 
the  number  of  functions  defined  in  the  funclist .data  file) .  A 
user  can  add  functions  to  the  system  by  creating  the  definition 
in  the  funclist.dat  file.  For  each  function  three  records  are 
required.  The  file  is  ASCII  and  can  be  easily  modified  using  any 
text  editor.  The  first  record  contains  the  name  of  the  ' .m, ' 
MATLAB  script,  file  containing  the  function.  The  second  record 
contains  the  label  to  be  shown  in  the  menu,  in  place  of 
FUNCTI0N1 ,  ...  FUNCTIONn.  The  third  record  contains  the  number 
of  data  series  required  by  the  function.  See  Appendix  G  for  an 
example  of  a  funclist.dat  file  constructed  in  this  way.  The 
select  series  menu  will  be  displayed  for  the  user  to  select  the 
series'  required  for  the  function.  Once  the  series'  are 
selected,  the  function  is  executed,  the  new  data  series  is  stored 
in  core  and  the  function  identification  number  is  entered  as 
(m+49) .  For  the  sample  menu  shown,  FUNCTI0N1  would  have  a 
function  identification  number  of  50;  and  the  user  is  prompted 
for  series  annotation  (see  discussion  for  create  core  data  for  a 
description  of  this  prompt) .  If  the  user  selects  only  the  QUIT 
option  from  the  select  series  menu,  no  data  will  be  processed  or 
stored. 

The  calling  syntax  for  the  function  must  be  as  follows: 

[stime,  inter,  data,  dtype]  =  fname(  cstimel,  cinterl, 
cdatal,  ...  cstimeN,  cinterN,  cdataN  ) 

The  returned  values  must  be  defined  by  the  function: 

'stime*  is  the  start  time  (or  value)  for  the  newly  created 
data. 

'inter'  is  the  interval  in  seconds  (or  appropriate 
increment)  for  the  new  data. 

'data'  is  the  array  containing  the  newly  created  data 
series. 
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•dtype'  is  the  data  type  for  the  newly  created  data  series 

(see  Appendix  A  for  value  descriptions) .  This  value  is 
used  only  if  the  data  series  is  later  written  to  a 
file. 

Three  input  values  will  be  sent  to  the  function  for  each  series 
selected  for  processing  by  this  function: 

'cstimeN, 1  where  N  is  an  integer  from  1  to  the  number  of 
series  required  for  the  function  as  defined  in  the 
funclist.dat  file,  cstime  is  the  start  time  for  the 
relevent  data  series. 

'cinterN, '  where  N  is  the  same  as  for  cstimeN.  cinter  is 
the  time  interval  for  the  relevent  data  series. 

•cdataN, '  where  N  is  the  same  as  for  cstimeN,  is  the  array 
of  data  values  that  constitute  the  series. 

MAT LAB  Command 

The  MATLAB  command  option  in  the  main  menu  will  allow  the  user  to 
enter  and  execute  MATLAB  commands.  The  message  and  prompt  for 
entering  MATLAB  commands  is  as  follows: 

Enter  MATLAB  commands  (return  to  quit) 
cmd> 

When  you  are  finished  and  wish  to  return  to  the  main  menu,  simply 
press  <return>. 

Output 

The  Output  option  of  the  main  menu  allows  the  user  to  output 
series  information  and  data  to  a  data  file.  The  menu  for  this 
mode  will  be  displayed  for  the  user's  response: 


OUTPUT 

Keyboard 

input 

Directory 

1 

File  Header 

2 

Series  Header 

3 

Data  Dump 

4 

ASCII  data 

5 

ORIGIN  command  file 

6 

QUIT 

0 

17 


Once  the  user  has  selected  an  option,  the  output  file  name  prompt 
will  be  displayed  for  the  user's  response: 

Provide  output  file  name  (def:  ?)  - 

The  default  file  name  is  temp.dat,  unless  the  ORIGIN  command  file 
option  is  selected.  The  default  file  name  for  the  ORIGIN  command 
file  option  is  \origin\origin.txt.  These  default  file  names  can 
be  found  in  the  include. m  file.  The  output  files  are  ASCII  data 
files. 

For  the  Directory  option  of  the  output  menu,  the  select  core/file 
menu  will  be  displayed.  If  file  is  selected,  then  the  select 
file  menu  will  be  displayed.  Once  core  or  the  specific  file  is 
selected  then  a  directory  listing  will  be  output  to  the  specified 
file.  The  directory  list  includes  series  number,  number  of  data 
values,  data  type,  start  time  {or  value) ,  time  interval  for  data 
values,  function  identification  number,  function  date  (if 
function  identification  number  is  not  zero) ,  and  series 
annotation.  See  Appendix  D  for  an  example.  For  a  hard  copy  of 
the  directory,  print  the  file  using  the  winodw  file  manager. 

For  the  File  Header  option  of  the  output  menu,  the  select  file 
menu  will  be  displayed  for  the  user's  response.  When  a  file  has 
been  selected,  the  ASCII  file  header  will  be  output  to  the 
specified  file.  See  Appendix  C  for  an  example. 

For  the  Series  Header  option  of  the  menu  the  select  core/file 
menu  will  be  displayed  for  the  user's  response.  If  file  is 
selected,  then  the  select  file  menu  will  be  displayed  for  the 
user's  response.  Finally,  the  select  series  menu  will  be 
displayed  for  the  user's  response.  Once  a  series  has  been 
selected,  the  series  header  information  is  output  to  the 
specified  file.  See  Appendix  E  for  an  example. 

For  the  Data  Dump  option  of  the  menu  the  select  core/ file  menu 
will  be  displayed  for  the  user's  response.  If  file  is  selected, 
then  the  select  file  menu  will  be  displayed  for  the  user's 
response.  Finally,  the  select  series  menu  will  be  displayed  for 
the  user's  response.  Once  a  series  has  been  selected,  the  user 
will  be  prompted  as  follows: 

Specify  start  (def:  1)  - 

Specify  increment  (def:l  )  - 

Specify  end  (def:  ?)  - 

The  default  for  the  ending  index  will  be  the  number  of  data 
values  contained  in  the  selected  series  or  the  number  required 
for  the  output  of  10  data  values,  the  smaller  of  these  two  values 
will  be  chosen.  Starting  at  the  specified  start  index  every  data 
value  will  be  output  for  an  increment  of  1,  every  other  data 
value  for  an  increment  of  2,  etc.,  to  the  specified  end  index. 
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The  output  will  include  the  index,  time  value,  and  data  value  for 
the  specified  range.  After  the  display  the  user  is  prompted: 

More  (def:Y  or  N) 

If  yes,  then  the  user  will  be  prompted  for  the  index  values  again 
and  the  specified  data  will  be  appended  to  the  specified  data 
file.  If  no,  control  returns  to  the  series  operations  menu. 

For  the  ASCII  data  option  of  the  menu  the  select  core/file  menu 
will  be  displayed  for  the  user's  response.  If  file  is  selected 
then  the  select  file  menu  will  be  displayed  for  the  user's 
response.  Finally,  the  select  series  menu  will  be  displayed  for 
the  user's  response.  Once  a  series  has  been  selected,  one  record 
will  be  output  for  each  data  value  in  the  series.  Each  record 
will  contain  two  values,  the  first  is  the  time  value  and  the 
second  is  the  series  data  value.  See  Appendix  H  for  an  example. 

For  the  ORIGIN  command  file  option  of  the  menu  the  select 
core/file  menu  will  be  displayed  for  the  user's  response.  If 
file  is  selected,  then  the  select  file  menu  will  be  displayed  for 
the  user's  response.  Finally,  the  select  series  menu  will  be 
displayed  for  the  user's  response.  Once  a  series  has  been 
selected,  the  user  will  be  prompted  for  extra  information  as 
follows: 

Enter  worksheet  name  (def:  matlab)  - 

Enter  first  column  name  (def:  T)  - 

Enter  second  column  name  (def:  D)  - 

Output  start  time  ?  (def:Y  or  N  for  resent  to  0)  - 

For  information  on  ORIGIN  worksheet  and  column  names  see 
reference  2.  For  start  time  the  ?  is  replaced  with  the  series 
start  time  (a  single  value) .  The  user  can  elect  to  adjust  time 
values  to  start  at  0.  The  output  for  this  option  is  an  ASCII 
file.  The  file  is  an  ORIGIN  script  file.  (The  file  can  be  run 
within  the  ORIGIN  script  window  to  load  series  data  into  an 
ORIGIN  work  sheet.)  See  Appendix  I  for  an  example.  If  this 
script  file  is  executed  under  origin,  then  the  data  will 
automatically  load  into  an  ORIGIN  worksheet,  ready  for  plotting. 

QUIT 

The  QUIT  option  exits  the  PAK  function.  The  user  will  be 
prompted  as  follows: 

Exit  program  (def:  Y  or  N  )  - 

The  user  is  given  a  chance  to  not  exit  the  program.  If  the  user 
does  exit  the  program,  then  the  user  is  prompted  as  follows: 

delete.dat  ..  keep  or  delete  [D]? 
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The  user  can  elect  to  keep  the  delete  disk  file  that  was  created. 
If  the  user  chooses  to  keep  the  file,  then  the  next  and  final 
prompt  will  be  as  follows: 

Desired  file  name  (def:  delete.dat)  - 
The  user  can  rename  the  file  to  create  a  new  output  series  file. 

DISCUSSION 

PAK  is  a  processing  system  designed  for  vectorized  time-series 
data.  The  user  can  create  and/or  manipulate  vectorized  data. 

The  system  is  written  in  MATLAB.  A  data  set  is  known  as  a 
series.  A  series  is  defined  by  series  number  for  identification, 
start  time  (or  start  value) ,  increment  for  start  time,  and  a  list 
of  data  values.  Other  values  are  stored  with  the  series  for 
documentation  purposes.  Input  files  can  contain  multiple  series, 
see  Appendix  A  for  data  file  format.  Series  are  stored  in  data 
files  or  in  memory  (called  core) .  See  Fig.  1  for  PAK  data  flow 
diagram.  Each  file  has  an  ASCII  file  header  for  documentation, 
followed  by  one  or  more  data  series. 

The  PAK  function  is  designed  to  process  vector  data.  The  user 
can  customize  the  system  by  modifying  the  file  that  contains  the 
list  of  valid  directories  and/or  the  file  that  contains  the  list 
of  data  processing  functions.  The  system  is  menu  operated  with 
some  keyboard  input  reguired;  or  an  input  parameter  file  can  be 
used  for  repeat  processing  operations.  When  the  program  is 
initiated,  the  user  selects  the  run  mode.  When  selecting 
core/file,  file  name,  or  series,  the  user  can  select  the  QUIT 
option  of  the  menu  to  exit  the  selected  operation.  The  system 
provides  output  for  use  with  ORIGIN  or  an  ASCII  list  file  of  the 
data  for  transporting  the  data  to  other  processing  systems. 

The  PAK  routines  described  here  only  cover  the  data  management 
"housekeeping"  functions  necessary  to  move  data  in  and  out  of  PAK 
storage,  delete  series,  and  create  and  modify  header  records.  The 
intent  was  to  create  a  skeleton  system  that  the  user  could  build 
upon  using  the  open  architecture  of  the  MATLAB  language  and  the 
script,  funclist.dat,  described  earlier.  The  user,  then,  can 
combine  several  MATLAB  functions  into  a  '.m*  file,  store  the  file 
in  a  toolbox,  and  modify  funclist.dat  appropriately  in  order  to 
include  his/her  favorite  functions  in  the  PAK.  This  process  will 
be  ongoing  in  the  Remote  Sensing  Applications  Branch  (Code  7240) 
at  the  Naval  Research  Laboratory  (NRL) .  User  comments  and/or 
contributed  functions  will  always  be  welcome. 

The  PAK  software  can  be  obtained  from  the  authors  or  by 
Anonymous  FTP  over  the  INTERNET.  The  following  UNIX  commands  will 
retrieve  a  copy  of  this  report  together  with  required  ' .dat' 
files  and  MATLAB  source  code  in  the  form  of  '.m'  subroutines: 
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Ftp_snaps . nrlssc . navy . mil 

anonymous 

cd  pub/pak 

binary 

get  pak.exe 


pak.exe  is  to  be  executed  under  the  MS-DOS  operating  system  and 
is  self -extracting.  The  resulting  files  will  be  a  series  of  .m 
files  and  two  .dat  files,  which  should  be  placed  in  a  MATLAB 
toolbox  named  'pak'  and  pak.wp,  which  is  a  copy  of  this  report  in 
wordperfect  format.  For  a  list  of  all  required  files  see 
Appendix  J. 
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Appendix  A 


Series  File  Format 


all  records  516  bytes 
record  1  (of  file) 

1-516  14(128)  info  (user  supplied) 

record  1  (of  series) 


1-4 

14 

series  number 

5-8 

14 

number  of  data  points 

9-12 

14 

number  of  data  records 

13-16 

14 

data  type 

1  intl6, 

2  int32, 

3  f lt32 , 

4  f lt64 , 

5  complex  f lt32 , f lt32 

6  complex  f lt64 , f lt64 

17-24 

F8 

seconds  since  Jan  1,  1968 

25-32 

F8 

interval  in  seconds 

33-36 

14 

function  ID 

37-40 

14 

function  year 

41-44 

14 

function  month 

45-48 

14 

function  day 

49-248 

14(50) 

series  annotation  (user  supplied) 

249-516 

misc. 

record  2-n  (of 

series) 

1-4 

14 

series  number 

5-516 

? 

data  of  type  specified 

in  header  record 

(pad  with  value  999999  to  complete 
partial  last  record  as  needed) 


record  n+1  (end  of  series) 

series  number  of  999999  and  pad  with  999999 

last  record  of  file  (end  of  file) 

series  number  of  999999  and  pad  with  999999 
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Appendix  B 

Sample  dirlist.dat  file 


a : \pak\ 
b : \pak\ 
c : \pak\ 
d:\pak 
e:\pak 
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Appendix  C 

Sample  File  Header  Listing 


delete  disk  file  header  created  using  th 
e  file  header,  create  option  of  the  pak 
function  the  data  in  this  file  create  Ma 
rch  9,  1994 
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Appendix  D 

Sample  Directory  listing 

Number  Data  Start  Time  Interval  Function  Function 

Series  Points  Type  (Start  Value)  Id  Date  Annotation 


116495  20  f lt32  100.0010  0.0010  002  Feb  24,  1994 

116505  20  f lt32  1000.0010  0.0010  000  test  series  a=l:20; 
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Appendix  E 

Sample  Series  Header  Listing 

Series  number  -  116505 

Number  of  points  -  20 

Data  type  -  fit 3 2 

Time  of  data  -  1000 

Data  interval  -  0.001 

function  -  000 

info  test  series  a=l:20; 

info 

info 

info 

info 
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Appendix  F 

Sample  Data  View  (Dump) 


1  ...  826991069.5400 

2  ...  826991070.0400 

3  ...  826991070.5400 

4  ...  826991071.0400 

5  ...  826991071.5400 

6  ...  826991072.0400 

7  ...  826991072.5400 

8  ...  826991073.0400 

9  ...  826991073.5400 

10  ...  826991074.0400 


1.0000000000 

2.0000000000 

3.0000000000 

4.0000000000 

5.0000000000 

6.0000000000 

7.0000000000 

8.0000000000 

9.0000000000 

10.0000000000 
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Appendix  6 

Sample  funclist.dat  File  Containing  Two  Entries 


pspec 

Elev  Pow  Spec 
1 

wvel 

Elev  Time  Ser 
1 
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Appendix  H 

Sample  ASCII  File  Listing 


1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 

1000 


0010000000 

1 

0020000000 

2 

0030000000 

3 

0040000000 

4 

0050000000 

5 

0060000000 

6 

0070000000 

7 

0080000000 

8 

0090000000 

9 

0100000000 

10 

0110000000 

11 

0120000000 

12 

0130000000 

13 

0140000000 

14 

0150000000 

15 

0160000000 

16 

0170000000 

17 

0180000000 

18 

0190000000 

19 

0200000000 

20 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 

0000000000 
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Appendix  I 

Sample  ORIGIN  Script  File  Listing 

create  matlab  -w  20  T  D 
matlab_T [ 1 ]  =  111.100000 

for(i=2 ;i<21;i+l) {matlab_T[i]  =  matlab_T[ i-1]  +  0.100000} 
matlab_D[l]=l. 000000 ;matlab_D[ 2 ] =1.414214 ;matlab_D[ 3 ]=l. 732051 ;ma 
tlab_D[4]=2. 000000 ;matlab_D[5]=2. 236068 ;matlab_D[6]=2. 449490 ;matl 
ab_D[7]=2. 645751 ;matlab_D[ 8] =2. 828427 ;matlab_D[9]=3.000000;matlab 
_D[ 10 ] =3 . 162278 ; 

matlab_D[ll]=3 .316625 ;matlab_D[12]=3 .464102 ;matlab_D[ 13 ]=3 . 605551 
;matlab_D[ 14]=3 . 741657 ;matlab_D[ 15]®3 . 872983 ;matlab_D[ 16]=4 . 00000 
0;matlab_D[ 17 ]=4 .123106  ?matlab_D[ 18]=4 . 242641 ?matlab_D[ 19]=4 .3588 
99 ;matlab_D[ 20 ]=4. 472136; 
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Appendix  J 


List  of  Files  Required  for  Running  PAK  and  WorkPerfect 
Documentation  File  Describing  the  System 


asciic.m 

serdelc.m 

asciif .m 

serdelf .m 

c2file.m 

serops.m 

cdir.m 

serseq.ro 

crdata . m 

strlen.m 

day 2 sec. m 

userfunc.m 

ddisp.m 

vdatac.m 

dfilter.m 

vdataf .m 

dirlist.dat 

wheader.m 

dispr.m 

wrdata.m 

dlistrd.m 

dofunc.m 

f check. m 

f delete . m 

f header. m 

file2c.m 

f ile2f .m 

filtc.m 

fixmat.m 

flistrd.m 

funclist.dat 

fverify.m 

getdate.m 

headerc.m 

header f .m 

i input. m 

include. m 

initpak.m 

mcomm.m 

mmenu . m 

msginput.m 

newcore.m 

newton . m 

originc.m 

originf .m 

pak.m 

pak.wp 

pakfunc.m 

pakout . m 

pspec . m 

rddata.m 

rheader.m 

sdir.m 

sec2day.m 

selserc.m 

selserf .m 

sercpy.m 
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